MacFormat 1997 January

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1997 January / macformat46.iso / Shareware Plus / Developers / EnterAct / EnterAct Stuff / Documentation / hAWK_BuiltIns.h < prev next >

Wrap

Text File | 1996-10-08 | 11.1 KB | 220 lines

/* hAWK_BuiltIns.h : add this to your EnterAct project and update your dictionary, then AutoLook will show definitions for hAWK's built-in variables and string and file functions. The type "hAWK_Builtin" is fictitious. To have a hAWK program eg "$MyProgram" built into your EnterAct dictionary change its name to "$$MyProgram.awk" and use the "File Extensions..." dialog to add the "awk" to the left or middle pane (your choice)--then add your hAWK program to your project and update your dictionary. You'll find the program also has a function marker menu (option-click in the window's title bar). */ //hAWK's built-in variables are: hAWK_Builtin ARGC//the number of input files plus one ; hAWK_Builtin ARGV /*array of command line arguments. The array is indexed from 0 to ARGC - 1, the input file names being ARGV[1] through ARGV[ARGC-1]. Dynamically changing the contents of ARGV can control the files used for data.*/ ; hAWK_Builtin FILENAME /*the name of the current input file. If no files are specified on the command line, the value of FILENAME is "-". A hAWK program may do all of its work in a BEGIN block, with no need for input (generating a list of random numbers for example).*/ ; hAWK_Builtin FNR/* the input record number in the current input file. Reset to 1 when starting a new input file. Hence the pattern “FNR == 1” detects the start of each file.*/ ; hAWK_Builtin FS/* the input field separator, a blank by default. If the default FS is used then leading blanks and tabs are trimmed from $1.*/ ; hAWK_Builtin IGNORECASE/* controls the case-sensitivity of all regular expression operations. If IGNORECASE has a non-zero value, then pattern matching in rules, field splitting with FS , regular expression matching with ~ and !~ , and the gsub() , index() , match() , split() , and sub() pre-defined functions will all ignore case when doing regular expression operations. Thus, if IGNORECASE is not equal to zero, /aB/ matches all of the strings "ab", "aB", "Ab", and "AB". The initial value of IGNORECASE is zero, so all regular expression operations are normally case-sensitive.*/ ; hAWK_Builtin NF// the number of fields in the current input record. ; hAWK_Builtin NR// the total number of input records seen so far. ; hAWK_Builtin OFMT// the output format for numbers, %.6g by default. ; hAWK_Builtin OFS// the output field separator, a blank by default. ; hAWK_Builtin ORS// the output record separator, by default a newline. ; hAWK_Builtin RS/* the input record separator, by default a newline. RS is exceptional in that only the first character of its string value is used for separating records. If RS is set to the null string, then records are separated by blank lines. When RS is set to the null string, then the newline character always acts as a field separator, in addition to whatever value FS may have.*/ ; hAWK_Builtin RSTART// the index of the first character matched by match(); 0 if no match. ; hAWK_Builtin RLENGTH// the length of the string matched by match(); -1 if no match. ; hAWK_Builtin SUBSEP/* the character used to separate multiple subscripts in array elements, by default "\034", some kinda up arrow very rare in text.*/ ; //(and three added for the Macintosh version) hAWK_Builtin RUNERR/* short for "run error", a file name that you can use to print your own error messages to, as in print "Error during run" > RUNERR. Default name is $tempRunErr, and you'll find the file in the same folder as $tempStdOut.*/ ; hAWK_Builtin STDPATH/* path name that can be prefixed to any file name you wish to be written to the same folder as stdout ($tempStdOut). Typically looks like "Disk:folder1...:folderN:" and typical use looks like outname = "MyOutFile" fullOutName = STDPATH outname; print "something" > fullOutName;*/ ; hAWK_Builtin TIME// at start of run, eg "Sunday, October 13, 1991 07:58 AM" ; // Built–in string functions gsub(r, s, t) /* for each substring matching the regular expression r in the string t , substitutes the string s , and returns the number of substitutions. If t is not supplied, uses $0 . */; index( s , t ) /* returns the index of the string t in the string s, or 0 if t is not present. */; length( s ) /* returns the length of the string s . */; match( s , r ) /* returns the position in s where the regular expression r occurs, or 0 if r is not present, and sets the values of RSTART and RLENGTH . */; split(s, a, r) /* splits the string s into the array a on the regular expression r , and returns the number of fields. If r is omitted, FS is used instead. */; sprintf( fmt , expr-list ) /* prints expr-list according to fmt , and returns the resulting string. See the discussion of “printf” for details. */; sub(r, s,t) /* this is just like gsub , but only the leftmost matching substring is replaced. Returns number of substitutions. */; substr(s, i, n) /* returns the n-character substring of s starting at i . If n is omitted, the rest of s is used. */; tolower( s ) /* returns a copy of the string s , with all the upper-case characters in s translated to their corresponding lower-case counterparts. Non-alphabetic characters are left unchanged. */; toupper( s ) /* returns a copy of the string s , with all the lower-case characters in s translated to their corresponding upper-case counterparts. Non-alphabetic characters are left unchanged. */; lookup ( s ) /* returns integer–coded C type of s (s should be a word). At present this function is supported only by EnterAct. Types are taken from whatever EnterAct project is open at the time. See “$LookupTest” for an example. Type integer returned ---- ------------ defined constant or macro 1 file–scope variable 2 function 4 enum constant 8 typedef 16 struct tag 32 union tag 64 enum tag 128 other 0 */; sort(a,b,s) /* produces an index in the array “b” that can be used to access the elements of “a” in sorted order. The string “s” specifies the kind of sort; "a" for ASCII, "n" for numeric, "d" for dictionary order, and "ra", "rn", "rd" for reverse of the same. Returns the number of elements in the array “b”, which is indexed numerically from 1 upwards. The elements of “b” are the indexes of “a” in sorted order provided “b” is accessed in the sequence b[1], b[2], b[3] etc. Typical use is maxIndex = sort(a, b, "d") for (i = 1; i <= maxIndex; ++i) print a[b[i]] which will print the elements of a in sorted dictionary order. See “$WordFrequency” and “$XRef_Full” for examples, and “$SortTest_Nums” for a simple numeric example. */; time ( ) /* returns the current time, eg "Sunday, October 27, 1991 09:03:30 AM" —note this is the time when the function is called, down to the second, whereas the TIME variable holds the time at which your program run starts, down to the minute. See “$TIME” for an example. */; prompt ( s ) /* displays an OK/Cancel dialog. The string “s” appears at the top of the dialog, and you can type in a string in an edit field. Returns what you type in, as though it was a string constant. Both the string “s” and what you type in are limited to 255 characters. For an example of usage see “$PromptTest” and “$YoungMath”. Typical use is x = prompt("Enter the number of lines to print:") if (x+0 > 0) { while (getline lne > 0 && ++i <= x) print lne } If you cancel the dialog or hit <Return.> without typing in any text, prompt returns the null string "". */; progress (s) /* displays the string “s” in a dialog on your screen (the message stays on the screen). You can change the message with another “progress” call. “progress” returns the number of times it has been called, and the dialog goes away by itself at the end of your program run. For a test sample, see “$ProgressTest”. */; //--and added for hAWK version 2 (mainly file functions): beep( n ) /* does a SysBeep(n); if the duration "n" is <= 0, the menu bar will flash instead. Durations of 0,1,2,5 work best. */; copy( s, t ) /* copies the file named “s” to the file named “t”. Both file names must be full pathnames (disk:folder:...folder:filename). Either the location or name or both can be changed. If file “t” already exists, it must be closed and unlocked. Both creator and type are preserved, and the resource fork is copied as well as the data fork. Any kind of file can be copied. To move or rename a file, use if (copy(s,t)) remove(s) (note this is an efficient way to move a file, but not a very fast way to rename one). Returns 1 if successful, 0 if the copy could not be done. */; exists( s ) /* returns 1 if the file named “s” exists, 0 if it does not. Any kind of file can be tested. */; fdate( s ) /* returns date/time of last modification of file named “s”, format “yr:mo:day:hr:min:sec” where yr is 4 digits, and the rest are 2 (eg always 01 rather than just 1). The length of the string is always 19 (or 0 if no date could be extracted) and the colons and digits always occupy the same positions. */; fsize( s ) /* returns size in bytes of the data fork only of the file named “s” */; getclip( n ) /* returns the calling application’s current clipboard text, up to a maximum of the first “n” bytes. Use n = 0 or omit it entirely if you want the entire clipboard. For example, if the current clip is “Some text here” then getclip(6) returns “Some t” whereas getclip(0) or getclip() returns the entire clip. At present this function is supported by: EnterAct. */; list( s, a ) /* given file or directory full pathname in “s”, produces list of full pathnames for all TEXT files in the directory (either the directory named or the directory holding the file), as elements indexed 1,2,3... in the array “a”. Note subdirectories are also excluded. Returns the number of files in the list. */; nested( s, a ) /* given a file full pathname in “s”, generates list of full pathnames for directories at the same level ("sibling folders"); given directory name, generates list of subdirectories at the top level in the named directory (“offspring directories”). The list is returned as elements indexed 1,2,3... in the array “a”. In other words, the same as “list” but for folders rather than TEXT files. Note neither “list” nor “nested” look beneath the top level of the folder in question. Returns the number of directories in the list. */; remove( s ) /* deletes the file named “s”, provided it is closed and unlocked. Use with caution, this is not undoable unless you get lucky using your favourite file recovery tool. Returns 1 if the file was deleted, 0 otherwise. */; rename( s, t ) /* takes the file with full pathname “s”, and renames it “t”. The new name “t” can be a full pathname, or just the new file name proper, as in rename("Disk:dir1:aardvark", "Disk:dir1:fruitbat") or equivalently rename("Disk:dir1:aardvark", "fruitbat") This function works only with files, not directories or volumes, returning 1 if the rename was carried out, 0 if not. */;